
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
  <head>
    <meta charset="utf-8" />
    <title>hmac --- 基于密钥的消息验证 &#8212; Python 3.7.8 文档</title>
    <link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/translations.js"></script>
    
    <script type="text/javascript" src="../_static/sidebar.js"></script>
    
    <link rel="search" type="application/opensearchdescription+xml"
          title="在 Python 3.7.8 文档 中搜索"
          href="../_static/opensearch.xml"/>
    <link rel="author" title="关于这些文档" href="../about.html" />
    <link rel="index" title="索引" href="../genindex.html" />
    <link rel="search" title="搜索" href="../search.html" />
    <link rel="copyright" title="版权所有" href="../copyright.html" />
    <link rel="next" title="secrets --- 生成安全随机数字用于管理密码" href="secrets.html" />
    <link rel="prev" title="hashlib --- 安全哈希与消息摘要" href="hashlib.html" />
    <link rel="shortcut icon" type="image/png" href="../_static/py.png" />
    <link rel="canonical" href="https://docs.python.org/3/library/hmac.html" />
    
    <script type="text/javascript" src="../_static/copybutton.js"></script>
    
    
    
    
    <style>
      @media only screen {
        table.full-width-table {
            width: 100%;
        }
      }
    </style>
 

  </head><body>
  
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>导航</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="总目录"
             accesskey="I">索引</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python 模块索引"
             >模块</a> |</li>
        <li class="right" >
          <a href="secrets.html" title="secrets --- 生成安全随机数字用于管理密码"
             accesskey="N">下一页</a> |</li>
        <li class="right" >
          <a href="hashlib.html" title="hashlib --- 安全哈希与消息摘要"
             accesskey="P">上一页</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="https://www.python.org/">Python</a> &#187;</li>
        <li>
          <a href="../index.html">3.7.8 Documentation</a> &#187;
        </li>

          <li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="crypto.html" accesskey="U">加密服务</a> &#187;</li>
    <li class="right">
        

    <div class="inline-search" style="display: none" role="search">
        <form class="inline-search" action="../search.html" method="get">
          <input placeholder="快速搜索" type="text" name="q" />
          <input type="submit" value="转向" />
          <input type="hidden" name="check_keywords" value="yes" />
          <input type="hidden" name="area" value="default" />
        </form>
    </div>
    <script type="text/javascript">$('.inline-search').show(0);</script>
         |
    </li>

      </ul>
    </div>    

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="module-hmac">
<span id="hmac-keyed-hashing-for-message-authentication"></span><h1><a class="reference internal" href="#module-hmac" title="hmac: Keyed-Hashing for Message Authentication (HMAC) implementation"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hmac</span></code></a> --- 基于密钥的消息验证<a class="headerlink" href="#module-hmac" title="永久链接至标题">¶</a></h1>
<p><strong>源代码:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/hmac.py">Lib/hmac.py</a></p>
<hr class="docutils" />
<p>此模块实现了 HMAC 算法，算法的描述参见 <span class="target" id="index-2"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2104.html"><strong>RFC 2104</strong></a>。</p>
<dl class="function">
<dt id="hmac.new">
<code class="sig-prename descclassname">hmac.</code><code class="sig-name descname">new</code><span class="sig-paren">(</span><em class="sig-param">key</em>, <em class="sig-param">msg=None</em>, <em class="sig-param">digestmod=None</em><span class="sig-paren">)</span><a class="headerlink" href="#hmac.new" title="永久链接至目标">¶</a></dt>
<dd><p>返回一个新的 hmac 对象。 <em>key</em> 是一个指定密钥的 bytes 或 bytearray 对象。 如果提供了 <em>msg</em>，将会调用 <code class="docutils literal notranslate"><span class="pre">update(msg)</span></code> 方法。 <em>digestmod</em> 为 HMAC 对象要使用的摘要名称、摘要构造器或模块。 它支持任何适用于 <a class="reference internal" href="hashlib.html#hashlib.new" title="hashlib.new"><code class="xref py py-func docutils literal notranslate"><span class="pre">hashlib.new()</span></code></a> 的名称并默认设为 <code class="xref py py-data docutils literal notranslate"><span class="pre">hashlib.md5</span></code> 构造器。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.4 版更改: </span>形参 <em>key</em> 可以为 bytes 或 bytearray 对象。 形参 <em>msg</em> 可以为 <a class="reference internal" href="hashlib.html#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code></a> 所支持的任意类型。 形参 <em>digestmod</em> 可以为某种哈希算法的名称。</p>
</div>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 3.4, will be removed in version 3.8: </span>MD5 作为 <em>digestmod</em> 的隐式默认摘要已被弃用。</p>
</div>
</dd></dl>

<dl class="function">
<dt id="hmac.digest">
<code class="sig-prename descclassname">hmac.</code><code class="sig-name descname">digest</code><span class="sig-paren">(</span><em class="sig-param">key</em>, <em class="sig-param">msg</em>, <em class="sig-param">digest</em><span class="sig-paren">)</span><a class="headerlink" href="#hmac.digest" title="永久链接至目标">¶</a></dt>
<dd><p>基于给定密钥 <em>key</em> 和 <em>digest</em> 返回 <em>msg</em> 的摘要。 此函数等价于 <code class="docutils literal notranslate"><span class="pre">HMAC(key,</span> <span class="pre">msg,</span> <span class="pre">digest).digest()</span></code>，但使用了优化的 C 或内联实现，对放入内存的消息能处理得更快。 形参 <em>key</em>, <em>msg</em> 和 <em>digest</em> 具有与 <a class="reference internal" href="#hmac.new" title="hmac.new"><code class="xref py py-func docutils literal notranslate"><span class="pre">new()</span></code></a> 中相同的含义。</p>
<p>作为 CPython 的实现细节，优化的 C 实现仅当 <em>digest</em> 为字符串并且是一个 OpenSSL 所支持的摘要算法的名称时才会被使用。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.7 新版功能.</span></p>
</div>
</dd></dl>

<p>HMAC 对象具有下列方法:</p>
<dl class="method">
<dt id="hmac.HMAC.update">
<code class="sig-prename descclassname">HMAC.</code><code class="sig-name descname">update</code><span class="sig-paren">(</span><em class="sig-param">msg</em><span class="sig-paren">)</span><a class="headerlink" href="#hmac.HMAC.update" title="永久链接至目标">¶</a></dt>
<dd><p>用 <em>msg</em> 来更新 hmac 对象。 重复调用相当于单次调用并传入所有参数的拼接结果: <code class="docutils literal notranslate"><span class="pre">m.update(a);</span> <span class="pre">m.update(b)</span></code> 等价于 <code class="docutils literal notranslate"><span class="pre">m.update(a</span> <span class="pre">+</span> <span class="pre">b)</span></code>。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.4 版更改: </span>形参 <em>msg</em> 可以为 <a class="reference internal" href="hashlib.html#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code></a> 所支持的任何类型。</p>
</div>
</dd></dl>

<dl class="method">
<dt id="hmac.HMAC.digest">
<code class="sig-prename descclassname">HMAC.</code><code class="sig-name descname">digest</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#hmac.HMAC.digest" title="永久链接至目标">¶</a></dt>
<dd><p>返回当前已传给 <a class="reference internal" href="#hmac.HMAC.update" title="hmac.HMAC.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">update()</span></code></a> 方法的字节串数据的摘要。 这个字节串数据的长度将与传给构造器的摘要的长度 <em>digest_size</em> 相同。 它可以包含非 ASCII 的字节，包括 NUL 字节。</p>
<div class="admonition warning">
<p class="admonition-title">警告</p>
<p>在验证例程运行期间将 <a class="reference internal" href="#hmac.digest" title="hmac.digest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">digest()</span></code></a> 的输出与外部提供的摘要进行比较时，建议使用 <a class="reference internal" href="#hmac.compare_digest" title="hmac.compare_digest"><code class="xref py py-func docutils literal notranslate"><span class="pre">compare_digest()</span></code></a> 函数而不是 <code class="docutils literal notranslate"><span class="pre">==</span></code> 运算符以减少定时攻击防御力的不足。</p>
</div>
</dd></dl>

<dl class="method">
<dt id="hmac.HMAC.hexdigest">
<code class="sig-prename descclassname">HMAC.</code><code class="sig-name descname">hexdigest</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#hmac.HMAC.hexdigest" title="永久链接至目标">¶</a></dt>
<dd><p>类似于 <a class="reference internal" href="#hmac.digest" title="hmac.digest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">digest()</span></code></a> 但摘要会以两倍长度字符串的形式返回，其中仅包含十六进制数码。 这可以被用于在电子邮件或其他非二进制环境中安全地交换数据值。</p>
<div class="admonition warning">
<p class="admonition-title">警告</p>
<p>在验证例程运行期间将 <a class="reference internal" href="#hmac.HMAC.hexdigest" title="hmac.HMAC.hexdigest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hexdigest()</span></code></a> 的输出与外部提供的摘要进行比较时，建议使用 <a class="reference internal" href="#hmac.compare_digest" title="hmac.compare_digest"><code class="xref py py-func docutils literal notranslate"><span class="pre">compare_digest()</span></code></a> 函数而不是 <code class="docutils literal notranslate"><span class="pre">==</span></code> 运算符以减少定时攻击防御力的不足。</p>
</div>
</dd></dl>

<dl class="method">
<dt id="hmac.HMAC.copy">
<code class="sig-prename descclassname">HMAC.</code><code class="sig-name descname">copy</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#hmac.HMAC.copy" title="永久链接至目标">¶</a></dt>
<dd><p>返回 hmac 对象的副本（“克隆）。 这可被用来高效地计算共享相同初始子串的数据的摘要。</p>
</dd></dl>

<p>hash 对象具有以下属性：</p>
<dl class="attribute">
<dt id="hmac.HMAC.digest_size">
<code class="sig-prename descclassname">HMAC.</code><code class="sig-name descname">digest_size</code><a class="headerlink" href="#hmac.HMAC.digest_size" title="永久链接至目标">¶</a></dt>
<dd><p>以字节表示的结果 HMAC 摘要的大小。</p>
</dd></dl>

<dl class="attribute">
<dt id="hmac.HMAC.block_size">
<code class="sig-prename descclassname">HMAC.</code><code class="sig-name descname">block_size</code><a class="headerlink" href="#hmac.HMAC.block_size" title="永久链接至目标">¶</a></dt>
<dd><p>以字节表示的哈希算法的内部块大小。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.4 新版功能.</span></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="hmac.HMAC.name">
<code class="sig-prename descclassname">HMAC.</code><code class="sig-name descname">name</code><a class="headerlink" href="#hmac.HMAC.name" title="永久链接至目标">¶</a></dt>
<dd><p>HMAC 的规范名称，总是为小写形式，例如 <code class="docutils literal notranslate"><span class="pre">hmac-md5</span></code>。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.4 新版功能.</span></p>
</div>
</dd></dl>

<p>这个模块还提供了下列辅助函数:</p>
<dl class="function">
<dt id="hmac.compare_digest">
<code class="sig-prename descclassname">hmac.</code><code class="sig-name descname">compare_digest</code><span class="sig-paren">(</span><em class="sig-param">a</em>, <em class="sig-param">b</em><span class="sig-paren">)</span><a class="headerlink" href="#hmac.compare_digest" title="永久链接至目标">¶</a></dt>
<dd><p>返回 <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></code>。 此函数使用一种经专门设计的方式通过避免基于内容的短路行为来防止定时分析，使得它适合处理密码。 <em>a</em> 和 <em>b</em> 必须为相同的类型：或者是 <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> (仅限 ASCII 字符，如 <a class="reference internal" href="#hmac.HMAC.hexdigest" title="hmac.HMAC.hexdigest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">HMAC.hexdigest()</span></code></a> 的返回值)，或者是 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>。</p>
<div class="admonition note">
<p class="admonition-title">注解</p>
<p>如果 <em>a</em> 和 <em>b</em> 具有不同的长度，或者如果发生了错误，定时攻击在理论上可以获取有关 <em>a</em> 和 <em>b</em> 的类型和长度信息 — 但不能获取它们的值。</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">3.3 新版功能.</span></p>
</div>
</dd></dl>

<div class="admonition seealso">
<p class="admonition-title">参见</p>
<dl class="simple">
<dt>模块 <a class="reference internal" href="hashlib.html#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code></a></dt><dd><p>提供安全哈希函数的 Python 模块。</p>
</dd>
</dl>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h4>上一个主题</h4>
  <p class="topless"><a href="hashlib.html"
                        title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code> --- 安全哈希与消息摘要</a></p>
  <h4>下一个主题</h4>
  <p class="topless"><a href="secrets.html"
                        title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">secrets</span></code> --- 生成安全随机数字用于管理密码</a></p>
  <div role="note" aria-label="source link">
    <h3>本页</h3>
    <ul class="this-page-menu">
      <li><a href="../bugs.html">提交 Bug</a></li>
      <li>
        <a href="https://github.com/python/cpython/blob/3.7/Doc/library/hmac.rst"
            rel="nofollow">显示源代码
        </a>
      </li>
    </ul>
  </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>  
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>导航</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="总目录"
             >索引</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python 模块索引"
             >模块</a> |</li>
        <li class="right" >
          <a href="secrets.html" title="secrets --- 生成安全随机数字用于管理密码"
             >下一页</a> |</li>
        <li class="right" >
          <a href="hashlib.html" title="hashlib --- 安全哈希与消息摘要"
             >上一页</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="https://www.python.org/">Python</a> &#187;</li>
        <li>
          <a href="../index.html">3.7.8 Documentation</a> &#187;
        </li>

          <li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="crypto.html" >加密服务</a> &#187;</li>
    <li class="right">
        

    <div class="inline-search" style="display: none" role="search">
        <form class="inline-search" action="../search.html" method="get">
          <input placeholder="快速搜索" type="text" name="q" />
          <input type="submit" value="转向" />
          <input type="hidden" name="check_keywords" value="yes" />
          <input type="hidden" name="area" value="default" />
        </form>
    </div>
    <script type="text/javascript">$('.inline-search').show(0);</script>
         |
    </li>

      </ul>
    </div>  
    <div class="footer">
    &copy; <a href="../copyright.html">版权所有</a> 2001-2020, Python Software Foundation.
    <br />
    Python 软件基金会是一个非盈利组织。
    <a href="https://www.python.org/psf/donations/">请捐助。</a>
    <br />
    最后更新于 6月 29, 2020.
    <a href="../bugs.html">发现了问题</a>？
    <br />
    使用<a href="http://sphinx.pocoo.org/">Sphinx</a>2.3.1 创建。
    </div>

  </body>
</html>